home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / setjmp.doc < prev    next >
Text File  |  1993-07-05  |  3KB  |  120 lines
  1.  
  2.     SETJMP.DOC (c)Copyright 1990-91, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/setjmp/setjmp
  7. c.lib/setjmp/longjmp
  8.  
  9.  
  10. setjmp/setjmp                        setjmp/setjmp
  11. setjmp/longjmp                        setjmp/longjmp
  12.  
  13.    NAME
  14.     setjmp    - save procedure context for future long jump
  15.     longjmp - jump to a previously saved procedure context
  16.  
  17.    SYNOPSIS
  18.     #include <setjmp.h>
  19.  
  20.     int r = setjmp(enviro);
  21.     (void) longjmp(enviro, rval)
  22.  
  23.     jmp_buf enviro;
  24.     int rval;
  25.  
  26.    FUNCTION
  27.     setjmp stores the current procedure context into an enviroment
  28.     array whos type is jmp_buf.  When called by a procedure it
  29.     saves the enviroment and returns 0.
  30.  
  31.     longjmp jumps to a previously saved enviroment causing execution
  32.     to begin at the setjmp call that saved that enviroment, but instead
  33.     of returning 0 the 'resumed' setjmp returns a return value set
  34.     by the longjmp call.
  35.  
  36.     jmp_buf is a typedef of an array, thus passing a jmp_buf structure
  37.     really passes the address of it.
  38.  
  39.     setjmp()/longjmp() is fully compatible with dynamic stacks (-gs
  40.     option to DCC).
  41.  
  42.    WARNING
  43.     You can only longjmp to a previously saved enviroment that has not
  44.     been unstacked.  In the example below main() is still stacked when
  45.     the longjmp occurs and is thus valid.
  46.  
  47.     It would be illegal to, say, call a subroutine which does a
  48.     setjmp and RETURNS to you, then longjmp back to that subroutine.
  49.  
  50.     The contents of the jmp_buf structure is private and may not
  51.     be modified by the program.
  52.  
  53.     WARNING WARNING
  54.     setjmp saves the current state of the registers, but not any registers
  55.     that get modified between the setjmp and the longjmp!!!  Thus, auto
  56.     variables placed in registers (which is done so automatically under
  57.     DICE) may contain 'old' values after a longjmp() if they were modified
  58.     after the setjmp().  To prevent this such variables must, by ANSI
  59.     convention, be made volatile.  The volatile qualifier forces an auto
  60.     variable to be placed on the stack instead of in a register.
  61.  
  62.    EXAMPLE
  63.     /*
  64.      *  run the program 1> sampleprg, it will print "Break Me With..."
  65.      *  continuously until you type ^C to break the program.  The
  66.      *  onbreak() vector takes over and longjmp's back to main.
  67.      */
  68.  
  69.     #include <stdio.h>
  70.     #include <setjmp.h>
  71.  
  72.     jmp_buf x;
  73.  
  74.     /*
  75.      *  even though the onbreak call is supposed to return, we can
  76.      *  longjmp out of it as well.
  77.      */
  78.  
  79.     int brk(void);
  80.     void breakme(void);
  81.  
  82.     main()
  83.     {
  84.         int r;
  85.  
  86.         onbreak(brk);
  87.         r = setjmp(x);      /*  returns 0 when called by main */
  88.         if (r == 0) {
  89.         for (;;)
  90.             breakme();
  91.         }
  92.                 /*  returns rval when longjmp'd to */
  93.         printf("Broke and jumped, r = %d\n", r);
  94.         return(0);
  95.     }
  96.  
  97.     int
  98.     brk()
  99.     {
  100.         longjmp(x, 23);
  101.     }
  102.  
  103.     void
  104.     breakme()
  105.     {
  106.         puts("Break Me With ^C!");
  107.     }
  108.  
  109.    INPUTS
  110.     jmp_buf enviro;     enviroment structure
  111.     int    rval;        return value (longjmp call)
  112.  
  113.    RESULTS (setjmp)
  114.     int    r;        0 when called directly, rval when enviroment
  115.                 restored by a longjmp
  116.  
  117.    SEE ALSO
  118.     onbreak, signal
  119.  
  120.